/*
 * Scenario.java
 *
 * Created on September 27, 2007, 8:03 PM
 *
 * Copyright 2008 David D. Emory
 * 
 * This file is part of Five Points. See <http://www.fpdev.org> for
 * additional information regarding the project.
 * 
 * Five Points is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * Five Points is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with Five Points.  If not, see <http://www.gnu.org/licenses/>.
 */
package org.fpdev.core;

import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import java.util.Set;

/**
 * A Scenario consists of a specific network and associated transit routes. A
 * DataPackage always contains at least one Scenario, called the <i>base</i> 
 * scenario, and may include any number of additional <i>derived</i> scenarios.
 * 
 * In practice, derived Scenarios will typically be used to model one or more
 * "vision" concepts for an expanded transit and/or bike facility system, while
 * the base scenario will represent the existing system. 
 *
 * Scenarios are hierarchical; any Scenario (except the base) extends from a
 * parent, and by default inherits all network and transit element, with the
 * option for modifications to the parent.
 * 
 * @author demory
 */
public class Scenario {

  private short id_;
  private String name_;
  private Scenario parent_;
  private List<Scenario> children_;

  /**
   * Creates a new instance of Scenario. A parent scenario reference is
   * required (except in the case of the base sceanrio), and the parent/child
   * connection is created by this constructor during initialization of the
   * child instance. 
   * 
   * @param id a numeric (short) identifier 
   * @param name a descriptive name of the scenario
   * @param parent a reference to the parent, or null if this is the base scenario
   */
  public Scenario(short id, String name, Scenario parent) {
    id_ = id;
    name_ = name;
    parent_ = parent;

    children_ = new LinkedList<Scenario>();
    if (parent_ != null) {
      parent_.addChild(this);
    }
  }

  public short getID() {
    return id_;
  }

  public String getName() {
    return name_;
  }

  @Override
  public String toString() {
    return getName();
  }

  public void setName(String name) {
    name_ = name;
  }

  public void addChild(Scenario s) {
    children_.add(s);
  }

  public Iterator<Scenario> getChildren() {
    return children_.iterator();
  }

  public Set<Scenario> getDescendents() {
    Set<Scenario> ret = new HashSet<Scenario>();
    ret.addAll(children_);
    for(Scenario s : children_) ret.addAll(s.getDescendents());
    return ret;
  }

  public Scenario getParent() {
    return parent_;
  }

  /**
   * Checks is this scenario is "accessible" to another scenario reference 's'. 
   * This condition is satisfied iff the two scenario references are the same
   * or this scenario is a direct ancestor of 's' (see also isAncestor()).
   * 
   * Accessibility is an important concept in the context of validating 
   * link/node relationships in multi-scenario data packages. Specifically, a 
   * valid link may only connect two nodes whose containing scenarios are
   * accessible to that link's containing scenario.
   * 
   * @param s another scenario
   * @return true if this scenario is accessible to s
   */
  public boolean isAccessibleTo(Scenario s) {
    //System.out.println(this.getName()+" accessible to "+s.getName()+"?");
    return s == this || this.isAncestorOf(s);
  }
  
  /**
   * Checks if this scenario is a direct ancestor of another scenario 's'. For
   * this to be satisified, it must be possible to reach this link from 's' by
   * only following parent references. 
   * 
   * Note: if this and 's' both reference the same scenario, false is returned.
   * 
   * @param s another scenario
   * @return true if this scenario is a direct ancestor of s
   */
  public boolean isAncestorOf(Scenario s) {
    Scenario parent = s.parent_;
    while (parent != null) {
      if (parent == this) {
        return true;
      }
      parent = parent.parent_;
    }
    return false;
  }

}
